Improve documentation of 'warning-display-at-bottom'

* lisp/emacs-lisp/warnings.el (warning-display-at-bottom):
* doc/lispref/display.texi (Warning Options):
* doc/emacs/windows.texi (Temporary Displays):
* etc/NEWS: Improve documentation of 'warning-display-at-bottom'.
See https://lists.gnu.org/archive/html/emacs-devel/2025-07/msg00024.html
for more details.

diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi
index a992f26fcddbf9e6deac361d9c1fa6170b6d79c5..b2cb53ad883813d0f061800ccad39f70a2948030 100644 (file)
--- a/doc/emacs/windows.texi
+++ b/doc/emacs/windows.texi
@@ -585,6 +585,16 @@ can be controlled by customizing the options
 (@pxref{Temporary Displays,,Temporary Displays, elisp, The Emacs Lisp
 Reference Manual}), and cannot exceed the size of the containing frame.
 
+@cindex warning buffer, display
+@vindex warning-display-at-bottom
+  Buffers showing warnings (such as byte-compilation warnings,
+@pxref{Compilation Functions,, Byte Compilation Functions, elisp, The
+Emacs Lisp Reference Manual}) are also by default shown in a window at
+the bottom of the selected frame.  You can control this using the
+variable @code{warning-display-at-bottom}: if set to @code{nil}, Emacs
+will use the normal logic of @code{display-buffer} (@pxref{Window
+Choice}) instead, and you can customize that via
+@code{display-buffer-alist}.
 
 @node Window Convenience
 @section Convenience Features for Window Handling

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 3426e764e17e0afe768d8734057fd1ce1594ea07..f363b0442036c790478e42f5d88df59b4c500c04 100644 (file)
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -931,6 +931,18 @@ won't appear at all.
   These variables are used by users to control what happens
 when a Lisp program reports a warning.
 
+@defopt warning-display-at-bottom
+This user option controls the window in which the warnings buffer is
+shown.  By default, the value is @code{t}, and Emacs displays the
+warnings buffer in a window at the bottom of the selected frame,
+creating a new window there if needed.  If customized to @code{nil}, the
+warnings buffer will be shown using the default rules of
+@code{display-buffer} (@pxref{Choosing Window}); in that case the
+@code{warning} category can be used in @code{display-buffer-alist} to
+customize how @code{display-buffer} will display these buffers
+(@pxref{Buffer Display Action Alists}).
+@end defopt
+
 @defopt warning-minimum-level
 This user option specifies the minimum severity level that should be
 shown immediately to the user, by popping the warnings buffer in some

diff --git a/etc/NEWS b/etc/NEWS
index dfe4c65f1dd08e30b793e3e9b5cfcadf512b8816..c52929b6d382ab1fcb9e37108c939280eaa132ee 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -608,6 +608,14 @@ Homebrew.
 *** 'write-region-inhibit-fsync' now defaults to t in interactive mode.
 This is the default in batch mode since Emacs 24.
 
+*** Warnings are now by default displayed in a new window at frame's bottom.
+Previously, when the selected frame had horizontally-split windows,
+warnings were displayed in some window on the frame that was hard to
+predict in advance.  The default behavior was changed to always display
+the window showing the warnings at the bottom of the selected frame.
+Customize the new user option 'warning-display-at-bottom' to the nil
+value to get back the previous behavior.
+
 *** The default value of 'read-process-output-max' was increased to 65536.
 
 *** 'url-gateway-broken-resolution' is now obsolete.

diff --git a/lisp/emacs-lisp/warnings.el b/lisp/emacs-lisp/warnings.el
index f83e8d42fac2cd2e62950882a00b17692c9fb7b9..ee28be3fada1625e364454621220cf354fdf93d9 100644 (file)
--- a/lisp/emacs-lisp/warnings.el
+++ b/lisp/emacs-lisp/warnings.el
@@ -122,9 +122,18 @@ See also `warning-suppress-log-types'."
   :version "22.1")
 
 (defcustom warning-display-at-bottom t
-  "Display the warning buffer at the bottom of the screen.
-The output window will be scrolled to the bottom of the buffer
-to show the last warning message."
+  "Whether to display the warning buffer at the bottom of the screen.
+If this is non-nil (the default), Emacs will attempt to display the
+window showing the warning buffer at the bottom of the selected
+frame, whether by reusing the bottom-most window or by creating a
+new window at the bottom of the frame.  The resulting window will be
+scrolled to the bottom of the buffer to show the last warning message.
+
+If the value of this variable is nil, Emacs will display the warning
+buffer in some window, as determined by `display-buffer' and its
+customizations.  In particular, the category designated by the
+symbol `warning' can be used in `display-buffer-alist' to customize
+the display of this buffer."
   :type 'boolean
   :version "30.1")